---
id: admin
title: tctl v1.17 admin command reference
sidebar_label: admin
description: Experience the new Temporal CLI public preview, offering enhanced admin operations for Clusters, Workflows, and Databases. Provide feedback before tctl’s deprecation after v1.0 release.
toc_max_heading_level: 4
keywords:
  - cli
  - cli reference
  - db
  - history shards
  - tctl
  - temporal
  - temporal cli
  - temporal server
---

:::info Temporal CLI is now available

The public preview of [Temporal CLI](/cli) is now available.
We encourage you to begin using it and to provide feedback.

After the release of Temporal CLI v1.0, tctl will deprecate.

:::

A `tctl admin` command allows the user to run admin operations.

Modifiers:

#### --help

`tctl admin [--help | -h]`

## cluster

The `tctl admin cluster` command runs the administrator-level operations on a given Cluster.

`tctl admin cluster command [command modifiers] [arguments...]`

- [add_search_attributes](#add_search_attributes)
- [remove_search_attributes](#remove_search_attributes)
- [get_search_attributes](#get_search_attributes)
- [describe](#describe)
- [list](#list)
- [upsert_remote_cluster](#upsert_remote_cluster)
- [remove_remote_cluster](#upsert_remote_cluster)

### add_search_attributes

The `tctl admin cluster add-search-attributes` command allows Search Attributes to be added to a Cluster.
Custom Search Attributes can be used to make a Cluster more identifiable.

:::note
Due to Elasticsearch limitations, you can only add new custom Search Attributes. Existing Search Attributes cannot be renamed or removed from the Elasticsearch index.
:::

Use this command to add custom Search Attributes to your Temporal Cluster:

```bash
tctl admin cluster add-search-attributes --name <SearchAttributeName> --type <SearchAttributeValueType>
```

:::note
If you are adding custom Search Attributes to a Cluster running from the `docker-compose-es.yml` file in the [temporalio/docker-compose](https://github.com/temporalio/docker-compose) repo, make sure to increase the Docker memory to more than 6 GB.
:::

#### --skip_schema_update

Allows the user to skip the Elasticsearch index schema update.

:::note
This will only register in metadata.
:::

#### --name

The name of the Search Attribute to add. Names can have multiple values.

Search Attribute names are case sensitive.

#### --type

The type of Search Attribute to add.
Multiple values can be added at once.

Values: Text, Keyword, Int, Double, Bool, Datetime

### describe

The `tctl admin cluster describe` command provides information for the current Cluster.

The following modifier changes the behavior of the command:

#### --cluster_value

The name of the remote Cluster within the current Cluster.

This modifier is optional, and can default to the return of current Cluster information.

### get_search_attributes

The `tctl admin cluster get_search_attributes` command retrieves existing Search Attributes for a given Cluster.

The following modifier will change the behavior of the command:

#### --print_json

Prints the existing search attributes in JSON format.

### list

The `tctl admin cluster list` command lists Cluster information on the given Cluster.

Default: 100

The modifier below changes the behavior of the command:

#### --pagesize

The size of the page that the list is printed on.

### remove_remote_cluster

The `tctl admin cluster remove_remote_cluster` command removes remote Cluster information on the given Cluster.

The modifier below changes the behavior of the operation:

#### --cluster

The name of the remote Cluster to remove.

### remove_search_attributes

> The Temporal tctl documentation covers version 1.17 of the Temporal CLI.

The `tctl admin cluster remove-search-attributes` command removes custom Search Attribute metadata from a Cluster.
This operation has no effect on Elasticsearch index schema.

Use the following command to remove a [Search Attribute](/visibility#search-attribute) from a Cluster's metadata:

```bash
tctl admin cluster remove-search-attributes --name <SearchAttributeKey>
```

Only custom Search Attributes can be removed from a Cluster's metadata.
Default Search Attributes cannot be removed.

Removing a Search Attribute removes it from the Cluster's metadata but does not remove it from the Elasticsearch index.
This means that the Search Attribute can be added back later as the same type.
After a Search Attribute has been added to the Elasticsearch index, it cannot be changed.

The following modifier changes the behavior of the operation:

#### --name

Name of the Search Attribute to remove.

### upsert_remote_cluster

The `tctl admin cluster upsert_remote_cluster` command adds or updates remote Cluster information in the current Cluster.

#### --frontend_address

The remote Cluster frontend address.

#### --enable_connection

Enables remote Cluster connection.

## db

The `tctl admin db` command runs administrator-level operations on a given database.

### Usage

`tctl admin db command [command modifiers] [arguments...]`

### Commands

- [tctl admin db scan](#scan)
- [tctl admin db clean](#clean)

### clean

The `tctl admin db clean` command cleans corrupted [Workflow Executions](/workflows#workflow-execution) from the targeted database.

The modifiers below change the behavior of the command.

#### --db_engine

Type of DB engine to use

Default: `cassandra`
Value: `cassandra` | `mysql` | `postgres`

#### --db_address

Persistence address for the database.

Default: 127.0.0.1

#### --db_port

Persistence port for the DB.

Default: 9042

#### --username

Database username.

#### --password

Database password.

#### --keyspace

Database keyspace

Default: "temporal"

#### --input_directory

The directory which contains the corrupted [Workflow Execution](/workflows#workflow-execution) files from running [`scan`](#scan).

#### --lower_shard_bound

The minimum amount (inclusive) of corrupt shards to handle.

Default: 0

#### --upper_shard_bound

The maximum amount (exclusive) of corrupt shards to handle.

Default: 16384

#### --starting_rps

starting rps of database queries.

Default: 100

#### --rps

Target rps of database queries.

Default: 7000

#### --concurrency

Number of threads to handle a scan.

Default: 1000

#### --report_rate

The number of shards handled between each emittance of progress.

Default: 10

:::note

Enable `--tls` before using any of the following modifiers.

:::

#### --tls_cert_path

Where the tls client cert is located.

#### --tls_key_path

Where the tls key is located.

#### --tls_ca_pat

Where the tls ca is located.

#### --tls_server_name

The name of the Db tls server.

#### --tls_disable_host_verification

Disables verification of the DB tls hostname and server cert.

### scan

The `tctl admin db scan` command scans concrete Workflow Executions in a given database, and detects corrupted ones.

#### --db_engine

Type of DB engine to use

Default: `cassandra`
Value: `cassandra` | `mysql` | `postgres`

#### --db_address

Persistence address for the DB.

Default: 127.0.0.1

#### --db_port

Persistence port for the DB.

Default: 9042

#### --username

DB username.

#### --password

DB password.

#### --keyspace

DB keyspace

Default: "temporal"

#### --lower_shard_bound value

The minimum amount (inclusive) of corrupt shards to handle.

Default: 0

#### --upper_shard_bound

The maximum amount (exclusive) of corrupt shards to handle.

Default: 16384

#### --starting_rps

starting rps of database queries.

Default: 100

#### --rps value

Target rps of database queries.

Default: 7000

#### --pagesize

The size of the page used to query database executions.

Default: 500

#### --concurrency

Number of threads to handle a scan.

Default: 1000

#### --report_rate

The number of shards handled between each emittance of progress.

Default: 10

#### --tls

Enable TLS over the DB connection.

:::note

Enable `--tls` before using any of the following modifiers.

:::

#### --tls_cert_path

Where the tls client cert is located.

#### --tls_key_path

Where the tls key is located.

#### --tls_ca_path

Where the tls ca is located.

#### --tls_server_name

The name of the Db tls server.

#### --tls_disable_host_verification

Disables verification of the DB tls hostname and server cert.

## decode

The `tctl admin decode` command allows the user to decode payloads sent and received from executed Activities.

`tctl admin decode command [command modifiers] [arguments...]`

- [proto](#proto)
- [base64](#base64)

### base64

The `tctl admin decode base64` command decodes base64 Payloads.

#### --base64_data

Decoded data in base64 format.

#### --base64_file

Creates a file with data in base64 format.

### proto

The `tctl admin decode proto` command decodes the Payload to proto format.

#### --type

The full name of the proto type to decode the Payload to.

#### --hex_data

Decodes the data to hex format.

#### --hex_file

Creates a file with the decoded hex data.

#### --binary_file

Creates a file with the decoded binary data.

## dlq

The `tctl admin dlq` commands run admin operations on a given dead-letter queue (DLQ).

`tctl admin dlq command [command modifiers] [arguments...]`

- [tctl admin dlq read](#read)
- [tctl admin dlq purge](#purge)
- [tctl admin dlq merge](#merge)

### merge

The `tctl admib dlq merge` command allows dead-letter queue (DLQ) messages to be merged.

The messages must have TaskIds with an equal or lesser value than the given TaskId.

#### --dlq_type

The type of DLQ to manage.

Options: namespace, history

#### --cluster

Source cluster for the DLQ.

#### --shard_id

ShardId provided for the command.

#### --last_message_id

Identifies the last read message.

Default: 0

### purge

The `tctl admin dlq purge` command deletes DLQ messages that have a Task Id equal to or less than the provided Task Id.

#### --dlq_type

The type of DLQ to manage.

Options: namespace, history

#### --cluster

Source cluster for the DLQ.

#### --shard_id

ShardId provided for the command.

#### --last_message_id

Identifies the last read message.

Default: 0

### read

The `tctl admin dlq read` command reads out messages from the dead-letter queue (DLQ).

---

#### --dlq_type

The type of DLQ to manage.

Options: namespace, history

#### --cluster

Source cluster for the DLQ.

#### --shard_id

ShardId provided for the command.

#### --max_message_count

The maximum number of messages to fethc.

Default: 0

#### --last_message_id

Identifies the last read message.

Default: 0

#### --output_filename

Provides a file to write output to.

Output is written to stdout on default.

## history_host

The `tctl admin history_host` command runs an admin-level operation on the history host.

## Usage

`tctl admin history_host command [command options] [arguments...]`

## Commands

- [tctl admin history_host describe](#describe)
- [tctl admin history_host get_shardid](#get_shardid)

### describe

The `tctl admin history_host describe` command describes the internal information of history host.

The following modifiers change the behavior of the command.

#### --workflow_id

Alias: `-w`

The WorkflowId of the Workflow whose history host is to be described.

#### --history_address

The history address of the history host.

#### --shard_id

The Id of the shard that belongs to the history host.

#### --print_full

Print a full and detailed summary of the history host.

### get_shardid

The `tctl admin history_host get_shardid` command gets the `shardId` for a given `namespaceId` and `workflowId`.

The following modifiers change the behavior of this command.

#### --namespace_id

The `namespaceId` of the history host where we're getting the `shardId`.

#### --workflow_id

Alias: `-w`

The WorkflowId of the history host where we're getting the shardId.

#### --number_of_shards

The total amount of shards for the Temporal Cluster.

Default: 0

## membership

The `tctl admin membership` command allows admin operations to be run on membership items.

### Usage

`tctl admin membership command [command modifiers] [arguments...]`

### Commands

- [list_gossip](#list_gossip)
- [list_db](#list_db)

### list_db

The `tctl admin membership list_db` command lists the Cluster items in a targeted membership.

The following modifiers change the behavior of the command.

#### --heartbeated_within

Filters the list by last Heartbeat time.

{/* todo: add supported format list */}

#### --role

Filters the results by membership role.

Default: all
Values: all, frontend, history, matching, worker

### list_gossip

The `tctl admin membership list_gossip` command lists the ringpop membership items present on the targeted membership.

The following modifier changes the behavior of the command:

#### --role value

Filters the results by membership role

Default: all
Values: all, frontend, history, matching, worker

## shard

The `tctl admin shard` commands enable admin-level operations on a specified shard.

#### tctl admin shard commands

- [describe](#describe)
- [describe_task](#describe_task)
- [list_tasks](#list_tasks)
- [close_shard](#close_shard)
- [remove_task](#remove_task)

### close_shard

The `tctl admin shard close_shard` command closes a shard with an Id that corresponds to the value given in the command.

`tctl admin shard close_shard [command options] [arguments...]`

The modifier below will change the behavior and output of the command.

#### --shard_id value

ShardId managed by the Temporal Cluster.

### describe_task

The `tctl admin shard describe_task` command describes a specified Task's Task Id, Task type, shard Id, and task visibility timestamp.

The modifiers below control the output and behavior of the command. Enter all modifiers after the command as such:

`tctl admin shard describe_task <modifiers>`

#### --db_engine

The type of database (DB) engine for the shard to use.

Default: "cassandra"

Values: "cassandra", "mysql", "postgres"

{/* todo: examples */}

#### --db_address

Persistence address for the database.

Default: 127.0.0.1

#### --db_port

Persistence port for the database.

Default: 9042

#### --username

Username entered into the database.

#### --password

Password entered into the database.

#### --keyspace

Keyspace for the database.

default: "temporal"

#### --tls

Enables TLS over the database connection.

#### --tls_cert_path

DB tls client cert path.

Note: tls must be enabled

#### --tls_server_name

DB tls server name

Note: tls must be enabled

#### --tls_disable_host_verification

DB tls verify hostname and server cert

Note: tls must be enabled

#### --shard_id

Identifies the specified shard.

Default: 0

#### --task_id

Describes the task.

Default: 0

#### --task_type

The kind of Task that is targeted within a shard.

Default: transfer

Values: transfer, timer, replication

#### --task_timestamp

Task visibility timestamp in nanoseconds

Default: 0

#### --target_cluster

Temporal cluster for the shard to use.

Default: "active"

### describe

The `tctl admin shard describe` command shows the Id for the specified shard.

The modifier below controls the behavior of the command.

#### --shard_id value

The Id of the shard to describe

Default: 0

### list_tasks

The `tctl admin shard list_tasks` command will list the Tasks available for a given shard Id and Task type.

The modifiers below affect the output and behavior of the command.

#### --more

Lists more pages of list tasks.
The default setting is to list one page of 10 list tasks.

#### --pagesize value

The size of the result page.
Default: 10

#### --target_cluster value

Temporal cluster to use.
Default: "active"

#### --shard_id value

The ID of the shard

Default: 0

#### --task_type value

The type of Task.

Default: transfer
Values: transfer, timer, replication, visibility

#### --min_visibility_ts value

The minimum value that can be set as a Task Visibility timestamp.

Supported formats include:

- '2006-01-02T15:04:05+07:00'
- Raw UnixNano
- Time range (N-duration), where 0 < N < 1000000 and duration (full-notation/short-notation) can be:
  - second/s
  - minute/m
  - week/w
  - month/m
  - year/y

#### --max_visibility_ts value

The maximum value that can be set as a Task Visibility timestamp.

Supported formats:

- '2006-01-02T15:04:05+07:00'
- Raw UnixNano
- Time range (N-duration), where 0 < N < 1000000 and duration (full-notation/short-notation) can be:
  - second/s
  - minute/m
  - week/w
  - month/m
  - year/y

### remove_task

The `tctl admin shard remove_task` command removes a Task from the shard.

`tctl admin shard remove_task [command options] [arguments...]`

The Task removed must have values that matches what is given in the command line.

The modifiers below change the behavior of the command.

#### --shard_id value

The shardId for the Task to be removed.

Default: 0

#### --task_id value

The taskId for the Task to be removed.

Default: 0

#### --task_type value

The type of Task to remove.

Default: transfer

Values: transfer, timer, replication

#### --task_timestamp value

The task visibility timestamp, given in nanoseconds.

Default: 0

## workflow

The `tctl admin workflow` commands enable administrator-level operations on Workflow Executions.

`tctl admin workflow command [modifiers] [arguments...]`

- [show](#show)

- [describe](#describe)

- [refresh_tasks](#refresh_tasks)

- [delete](#delete)

### delete

The `tctl admin workflow delete` command deletes the current [Workflow Execution](/workflows#workflow-execution) and the mutableState record.

#### --db_engine value

The type of database (DB) engine to use.

Default: "cassandra"
Values: "cassandra", "mysql", "postgres"

#### --db_address value

Persistence address for the database.

Default: 127.0.0.1

#### --db_port value

Persistence port for the database.

Default: 9042

#### --username value

Username entered into the database.

#### --password value

Password entered into the database.

#### --keyspace value

Keyspace for the database.

default: "temporal"

#### --url value

URL of the Elasticsearch cluster.

Default: "http://127.0.0.1:9200"

#### --es-username value

Username for the Elasticsearch cluster.

#### --es-password value

Password for the Elasticsearch cluster.

#### --version value

The version of the Elasticsearch cluster for the Workflow.

Default: v7

Values: v6, v7

#### --index value

Elasticsearch index name.

#### --workflow_id value

Alias: `-w`

The Id of the current Workflow.

#### --run_id value

Alias: `-r`

The Id of the current run.

#### --skip_errors

Skip any errors that occur in the Workflow Execution.

#### --tls

Enables TLS over the database connection.

:::note

TLS must be enabled to use the following modifiers.

:::

#### --tls_cert_path value

DB tls client cert path.

Note: tls must be enabled

#### --tls_key_path value

DB tls client key path

Note: tls must be enabled

#### --tls_ca_path value

DB tls client ca path

Note: tls must be enabled

#### --tls_server_name value

DB tls server name

Note: tls must be enabled

#### --tls_disable_host_verification

DB tls verify hostname and server cert

Note: tls must be enabled

## describe

The `tctl admin workflow describe` command describes internal information of the current [Workflow Execution](/workflows#workflow-execution).

#### --workflow_id value

Alias: `-w`

The Id of the current Workflow.

#### --run_id value

Alias: `-r`

The Id of the current run.

## refresh_tasks

The `tctl admin workflow refresh_tasks` command updates all [Tasks](/workers#task) in a [Workflow](/workflows), provided that the command can fetch new information for Tasks.

#### --workflow_id value

Alias: `-w`

The Id of the current Workflow.

#### --run_id value

Alias: `-r`

The Id of the current run.

## show

The `tctl admin workflow show` command displays Workflow history from the database.

#### --workflow_id value

Alias: `-w`

The current Workflow.

#### --run_id value

Alias: `-r`

The current RunId.

#### --min_event_id value

The minimum Event Id to include in the history.

Default: 0

#### --max_event_id value

The maximum Event Id to include in the history.

Default: 0

#### --min_event_version value

The start Event version to be included in the history.

Default: 0

#### --max_event_version value

The end Event version to be included in the history.

Default: 0

#### --output_filename value

The file where the output is sent to.
